PPI 아키텍처 문서

마지막 업데이트 2026-08-04

문서 읽는 법 · 설명식

이 문서는 이렇게 읽으면 됩니다

PPI 프로젝트 아키텍처의 핵심을 설명식으로 먼저 안내합니다. 기술적 결론과 원문 근거는 아래 본문에 보존되어 있습니다.

핵심 흐름 펼쳐 보기

비유와 핵심 질문으로 먼저 전체 구조를 잡습니다.
실제 컴포넌트·파일·데이터 흐름을 따라 내려갑니다.
코드 라인과 주의사항에서 구현 근거를 확인합니다.

기존 본문 섹션에서 세부 근거를 이어서 확인합니다.

아동 대화 연습을 위한 AI 아바타 플랫폼 · Turborepo 모노레포 · LiveKit Agent(기본) / OpenAI Realtime + Mediasoup SFU

앱 (web, socket, stt, livekit-agent)

111+

페이지 / API 엔드포인트

커스텀 훅

UI 컴포넌트

섹션 컴포넌트

60+

유틸리티 파일

🗺 시스템 개요

치료사 (Host)

모니터링 + 피드백

아동 (Guest)

AI와 대화 연습

↕ WebRTC / Socket.io

apps/web

Next.js 16 · Port 3000

apps/socket

Socket.io + Mediasoup · Port 3001

apps/stt

Go · STT 처리 서버

apps/livekit-agent

Python · 핑퐁이 음성 에이전트

↕ AWS SDK

DynamoDB

프로필 · 로그 · 활동

AWS S3

음성 · 미디어 파일

OpenAI Realtime

핑퐁이 AI 아바타

Google STT

음성 인식

LiveKit Cloud SFU

AI 음성 전용 · 관리형

Valkey

세션 설정 configRef · peer 상태

Typecast TTS

아바타 보이스 합성

SFU가 둘이다 — AI 음성(LiveKit)과 수업 중계(mediasoup)

핑퐁이 음성 대화는 LiveKit Cloud SFU + apps/livekit-agent가, 수업 미디어(아동 영상·화면공유·진행자 모니터링)는 자체 mediasoup SFU(apps/socket)가 담당합니다. 두 SFU는 서로 통신하지 않고 아동 브라우저가 양쪽에 동시 참여해 다리를 놓습니다. 2026-08-03부터 신규 사용자 기본 대화 모드가 livekit(DEFAULT_CONVERSATION_MODE)이므로, 기본 경로는 OpenAI Realtime 단일 SFU가 아닌 이 2-SFU 구조입니다.

상세: LiveKit 음성 에이전트 흐름 & 두 SFU 구조

수업 흐름

아동은 /client-guest, 치료사는 /main/meet, 모니터는 /monitor-dashboard에서 접속합니다.

아동: 핑퐁이 AI와 직접 대화 연습
치료사: 아동 활동 모니터링 + 세션 제어
모니터: 자동 응답 · STT · LLM 개입
세션 로그 자동 기록 및 분석

FSD 아키텍처 레이어

Feature-Sliced Design 기반의 계층형 구조입니다.

pages — Next.js App Router 라우트
widgets — 재사용 UI 컴포넌트 묶음
features — 기능별 로직 (자동 응답, STT 등)
entities — 비즈니스 모델 · Zustand 상태
shared — 공유 타입 · 유틸 · UI

핑퐁이 AI 세션

런타임은 resolveVoiceSessionConfig()가 livekit / realtime / tts 중 하나로 정합니다. 신규 사용자 기본값은 livekit이며, 아바타에 Typecast 보이스가 없으면 Realtime으로 폴백합니다.

VAD 기반 음성 감지
실시간 STT · 전사 (Google Speech API)
턴별 세션 로그 기록
활동 단계별 프롬프트 제어

📦 앱 구조 (Turborepo)

apps/web · Next.js 16

메인 웹 애플리케이션. 치료사 대시보드, 게스트 수업, API 라우트 포함.

React 19.2.6 + TypeScript 5.9
Tailwind CSS 4.x
Zustand 5 · Socket.io Client
mediasoup-client 3.18
AWS DynamoDB · S3 SDK
Port: 3000

apps/socket · Node.js

Mediasoup SFU 전용 실시간 통신 서버. 게스트·호스트·모니터 시그널링 처리.

Socket.io 4.x (/sfu 네임스페이스)
Mediasoup 3.x (SFU)
Prometheus 메트릭
S3 녹음 업로드
REST API (rooms, peers, groups)
Port: 3001

apps/stt · Go

별도 운영 STT 처리 서버. Google Speech API 연동.

Google Speech API 연동
배치 처리 · 화자 분리
중복 제거 (dedup)
환각 감지 (hallucination)
WebSocket 클라이언트 연동

apps/livekit-agent · Python

핑퐁이 음성 에이전트 워커. 웹이 직접 호출하지 않고 토큰의 roomConfig.agents(RoomAgentDispatch)로 LiveKit 서버가 ppi-agent를 소환합니다.

livekit-agents ~1.6 (silero · turn-detector)
OpenAI Realtime STT/LLM + Typecast TTS
세션 설정은 Valkey configRef로 수신
RPC: setInputEnabled · setVadOptions · setAllowInterruptions · interrupt
data topic agent-event-log로 전사·턴 상태 송출
Python ≥ 3.11 · 별도 배포 워크플로우(dev/staging/prod)

🔌 Socket 서버 (/sfu 네임스페이스) 핸들러 구조

Transport · Media

getRouterRtpCapabilities
createWebRtcTransport
connectWebRtcTransport
produce (카메라·마이크·AI 오디오)
consume (스트림 구독)
newProducer / producerClosed

Room · Session

join-group / leave-group
session-start / session-stop
session-control (호스트 → 게스트)
chat-message (호스트 → 게스트)
avatar-info 교환
graceful disconnect

Monitoring · REST API

monitor-subscribe (모니터 구독)
monitoring-data (실시간 상태 전송)
GET /rooms — 활성 룸 목록
GET /rooms/:roomId — 룸 상세
GET /peers — 피어 목록
DELETE /groups/:id/peers

🗂 라우트 구조

UI 페이지

/main대시보드 홈

/main/meet/[roomId]호스트 수업 진행

/main/activity활동 관리

/main/log세션 로그 분석

/main/avatars아바타 관리

/main/prompt-test프롬프트 테스트

/main/schedule일정 관리

/main/curriculum커리큘럼 관리

/main/member치료사 관리

/main/user사용자(부모) 관리

/main/res리소스 관리

/main/class-mgmt클래스 관리

/client-guest아동 수업 입장 (PIN·이름·장치 선택)

/client-guest/session아동 수업 세션 (GuestLayout)

/monitor-dashboard모니터 대시보드 (예정·라이브 세션)

/monitor-dashboard/[group]/[roomId]개별 방 모니터링

API 엔드포인트 (주요)

/api/realtime/callOpenAI Realtime 세션 토큰

/api/activities활동 CRUD

/api/activity-templates활동 템플릿

/api/session-logs세션 로그

/api/lessons수업 CRUD

/api/avatars아바타 관리

/api/ice-serversICE 서버 정보

/api/resources미디어 리소스

/api/members치료사 계정

/api/users부모/아동 계정

/api/guest-data게스트 세션 데이터

/api/chat-presets치료사 채팅 프리셋

/api/recording-captions녹음 자막

/api/lesson-progress레슨 진행률

/api/classes수업 클래스

/api/health헬스체크

/metricsPrometheus 메트릭

⚡ 주요 코드 흐름

게스트 세션 흐름 (/client-guest)

엔트리

/client-guest
PIN · 이름 · 장치 선택

→

SFU 연결

use-mediasoup-socket
/sfu 네임스페이스

→

Device 초기화

use-mediasoup-device
RTP Capabilities 로드

→

미디어 발행

use-mediasoup-producer
카메라 · 마이크 produce

→

AI 세션

use-ai-session
OpenAI Realtime 연결

→

STT

use-external-stt
Google Speech API

→

AI 음성 발행

AI 오디오 스트림
SFU produce → 모니터 수신

→

로그 기록

use-session-logs
DynamoDB 저장

모니터 대시보드 흐름 (/monitor-dashboard)

대시보드

useMonitorUserId
라이브 · 예정 세션

→

SFU 구독

use-monitor-socket
게스트 스트림 consume

→

세션 관리

use-monitor-session
활동 · 스텝 상태 추적

→

자동 응답

features/monitor/
auto-response · auto-transition

→

외부 STT

features/monitor/
external-stt

→

전역 상태

use-monitor-data-store
rooms · sessions · toasts

호스트 흐름 (/main/meet/[roomId])

수업 입장

use-host-socket
SFU 룸 참여

→

스트림 수신

use-mediasoup-consumer
게스트 비디오 · AI 오디오

→

세션 제어

session-control
시작 · 중단 · 스텝 이동

→

채팅 피드백

host-chat-panel
프리셋 · 직접 입력

→

로그 분석

session-log-table
턴별 시각화

게스트 페이지 핵심 엔티티 구조

entities/guest-session 구성

use-ai-session — OpenAI Realtime 연결 관리
use-transcripts — 전사 결과 상태
use-guest-connection — 소켓 + Device 통합 연결
external-stt-observer — WebSocket STT 관찰자

entities/guest-page-session 구성

use-guest-page-session — 활동·스텝 상태 총괄
use-step-sync — 모니터와 스텝 동기화
use-step-transition — 스텝 전환 처리
use-auto-save-lesson-progress — 진행률 자동 저장

use-ai-session 제어 인터페이스

startSession(params) — 세션 시작
stopSession() — 세션 종료
sendTextMessage(text) — 텍스트 입력
interruptResponse() — AI 응답 중단
setMicrophoneEnabled(bool) — 마이크 ON/OFF
setNoiseReduction(mode) — 노이즈 감소
reloadSession() — 세션 재시작
jumpToStep(index) — 활동 단계 이동

🪝 주요 훅 목록

Mediasoup SFU (hooks/mediasoup/)

use-mediasoup-socketSFU 시그널링 소켓 연결 · 재연결 관리

use-mediasoup-deviceDevice 초기화 · RTP Capabilities 로드

use-mediasoup-producer카메라·마이크·AI 오디오 Producer 생성

use-mediasoup-consumer피어 스트림 Consumer (비디오·오디오 분리)

소켓 연결 (entities/)

use-guest-socket게스트 소켓 이벤트 처리

use-host-socket호스트 소켓 이벤트 처리

use-monitor-socket모니터 소켓 · SFU 구독

use-guest-connection소켓 + Device 통합 연결 (게스트용)

세션 · 페이지 상태 (entities/)

use-ai-sessionOpenAI Realtime API 연결 · 세션 관리

use-transcripts전사 결과 상태 관리

use-guest-page-session활동·스텝 상태 총괄 (게스트 페이지)

use-step-sync모니터와 스텝 동기화

use-step-transition스텝 전환 처리

use-auto-save-lesson-progress레슨 진행률 자동 저장

use-monitor-session모니터 세션 상태 관리

use-session-logs세션 로그 조회 및 관리

use-session-auto-finish자동 종료 조건 감지

use-session-log-table세션 로그 테이블 상태

미디어 · 오디오

use-camera-stream카메라 스트림 관리

use-local-media-stream로컬 미디어 스트림

use-device-manager미디어 장치 선택 관리

use-video-device-validator비디오 장치 유효성 검사

use-avatar-video아바타 비디오 스트림

use-volume-amplifier출력 음량 증폭

use-audio-processing-chain오디오 전처리 체인

use-media-cleanup미디어 리소스 정리

use-mfcc-log-collectorMFCC 패턴 로그 수집

STT · 음성인식

use-external-stt외부 STT (Google Speech API)

use-stt-fallbackSTT 폴백 처리

use-ai-audio-noise-guardAI 오디오 노이즈 가드

use-ai-english-guardAI 영어 가드 (한국어 강제)

use-transcript-english-matcher전사 결과 영어 매칭

use-recording-captions녹음 자막 관리

네트워크 · 모니터링

use-network-status네트워크 온라인 상태

use-network-recovery네트워크 복구 처리

use-monitor-network-level네트워크 레벨 수치 모니터링

use-guest-network-alert게스트 네트워크 경고

use-network-quality네트워크 품질 지표

use-monitor-user-id모니터 사용자 ID 관리

use-guest-controls모니터 → 게스트 제어

데이터 조회

use-activities활동 목록 조회

use-activity-templates활동 템플릿 조회

use-avatars / use-avatar아바타 목록 / 단건 조회

use-avatar-resources아바타 리소스 조회

use-users / use-user사용자(부모) 목록 / 단건

use-members / use-current-member치료사 목록 / 현재 계정

use-lessons수업 목록 조회

use-lesson-templates레슨 템플릿 조회

use-curriculums커리큘럼 조회

use-curriculum-categories커리큘럼 카테고리

use-resources미디어 리소스 조회

use-holidays휴일 정보 조회

use-prompt-variables프롬프트 변수 조회

use-vacations치료사 휴가 관리

기타 유틸리티

use-countdown카운트다운 타이머

use-cumulative-elapsed누적 경과 시간 측정

use-follow-bottom-scroll채팅 스크롤 추종

use-prevent-page-leave페이지 이탈 방지

use-scheduled-polling예약된 폴링 실행

use-mobile-screen모바일 화면 감지

use-kakao-browser-redirect카카오 인앱 브라우저 처리

use-recommended-browser권장 브라우저 가이드

use-resource-cache리소스 캐시 관리

use-resource-upload리소스 업로드 처리

use-sanitized-input입력값 정제

use-network-alert-config네트워크 경고 설정

🧩 FSD 컴포넌트 구조

레이어 의존 방향 (위 → 아래로만 참조 가능)

app/ (pages)

Next.js App Router 라우트

↓

widgets/

재사용 UI 묶음

↓

features/

기능별 로직

↓

entities/

비즈니스 모델 · 상태

↓

shared/

공유 타입 · 유틸 · UI

widgets/guest — 게스트 UI

guest-layout — 메인 레이아웃 컨테이너
guest-camera — 카메라 비디오
meet-avatar — 아바타 표시
meet-video — 호스트 비디오
transcript-panel — 실시간 전사 패널
session-error-screen — 에러 화면
resource-loading-screen — 리소스 로딩
network-toast — 네트워크 상태
status-header — 상태 표시 헤더
video-display — 비디오 표시

widgets/monitor-dashboard — 대시보드 UI

live-sessions — 라이브 세션 목록
today-scheduled — 오늘 예정 세션
test-session-manager — 테스트 세션
session-card — 세션 카드 컴포넌트
alerts-panel — 알림 패널

widgets/monitor — 모니터 UI

모니터링 룸 별 UI 컴포넌트

sections/ — 관리 화면 섹션

host-chat-panel — 호스트 채팅
host-video — 호스트 비디오
share-screen — 화면 공유
session-log-table — 세션 로그
activity-form / activity-table
avatar-form / avatar-list
step-table / step-form
curriculum-*.tsx (sidebar, detail)
performance-monitor — 성능 모니터

🏗 Features · Entities 상세

features/guest

entry-cleanup — 엔트리 정리
message-input — 메시지 입력 UI
session-control — 세션 시작·종료

features/monitor

room-monitoring — 방 모니터링
group-monitoring — 그룹 모니터링
auto-response — 자동 응답
auto-transition — 자동 스텝 전환
external-stt — 외부 STT
realtime-model — LLM 모델 제어
vad-settings — VAD 설정
lesson-completion — 레슨 완료

entities/guest-session

use-ai-session
use-transcripts
use-guest-connection
external-stt-observer

entities/guest-page-session

use-guest-page-session
use-step-sync
use-step-transition
use-auto-save-lesson-progress
use-noise-test-harness

entities/socket-connection

use-mediasoup-socket

entities/monitor

use-monitor-session
use-monitor-socket
use-monitor-user-id
use-guest-controls

entities/monitor-dashboard

use-sessions
use-upcoming-sessions

stores/ (Zustand)

use-monitor-data-store
rooms · sessions · toasts · alerts
use-monitor-ui-store
use-lesson-cache-store
use-session-log-audio-store
use-language-guard-settings-store
use-first-turn-korean-guide-store
use-admin-classes-store

contexts/

activities-context
activity-templates-context
members-context / users-context

🗄 데이터 레이어

DynamoDB 테이블

activity — 활동 데이터
activity-template — 활동 템플릿
session-log — 세션 로그 (턴별)
chat-log — 채팅 로그
chat-preset — 치료사 채팅 프리셋
member — 치료사 계정
user — 부모/아동 계정
lesson — 수업 정보
lesson-session — 레슨 세션
resource — 미디어 리소스
avatar — 아바타 데이터
curriculum — 커리큘럼
speech-alert-rule — 음성 경고 규칙

API 레이어 구조

lib/api/controllers/ — 요청 라우팅
lib/api/services/ — 비즈니스 로직
lib/api/dao/ — DynamoDB 직접 접근
lib/dynamodb.ts — 클라이언트 초기화
lib/dynamodb-utils.ts — 쿼리 헬퍼
lib/db-queries.ts — 공통 쿼리
lib/s3.ts — S3 파일 처리
lib/auth.middleware.ts — 인증 검증
lib/ppi-api-client.ts — 내부 API 클라이언트

TypeScript 타입 체계

types/db/ — 26개 DB 모델 타입
types/enum/ — 열거형 타입
types/props/ — 컴포넌트 Props
types/stt.types.ts — STT 관련 타입
types/mediasoup.types.ts — Mediasoup 타입
types/delegates.types.ts — 콜백 위임 타입
types/instruction-variables.types.ts
types/index.ts — barrel export

계층	파일 위치	역할	주요 항목
Controller	lib/api/controllers/	HTTP 요청 파싱 · 응답 포맷팅	guest-data, lesson-session
Service	lib/api/services/	비즈니스 로직 처리	guest-data, lesson-progress, resource
DAO	lib/api/dao/	DynamoDB 직접 CRUD	각 도메인별 DAO
Middleware	lib/auth.middleware.ts	API 인증 검증	토큰 기반 인증

⚙ 기술 스택

프론트엔드

React 19.2.6
Next.js 16.2.12
TypeScript 5.9.2
Tailwind CSS 4.1.14
Zustand 5.0.9
Socket.io Client 4.8.1
mediasoup-client 3.18.1

백엔드 / 서버

Node.js (LTS ≥ 20.9)
Express 4.x
Socket.io 4.x
Mediasoup 3.x (SFU)
Go (STT 서버)
Python ≥ 3.11 (LiveKit Agent)
MySQL2
prom-client

AI / 음성

OpenAI Realtime API
LiveKit Agents ~1.6 (Python)
Typecast TTS (아바타 보이스)
Google Speech API
VAD (Voice Activity Detection)
Web Audio API
MFCC 분석
노이즈 감소 필터
LogRocket 10.1.0

인프라 / 클라우드

AWS DynamoDB
AWS S3
AWS EC2 (ARM64)
AWS ALB · Route53
Docker / GHCR
Terraform
GitHub Actions (CI/CD)

☁ 인프라 및 배포

배포 아키텍처

GitHub → GitHub Actions (workflow_dispatch)

빌드 → Docker 이미지 빌드 · GHCR 푸시

프로비전 → Terraform으로 AWS 인프라 생성

DNS → {branch}-app. 자동 생성

정리 → EventBridge + Lambda (3일 후 자동 삭제)

모니터링

Prometheus 메트릭 (/metrics)
HTTP 요청 수 · 지연시간
Socket.io 접속 수
Mediasoup 워커 · 리소스 상태
Node.js 런타임 메트릭
서버 → JSON Lines (Loki 호환)
브라우저 → LogRocket 세션 기록
/api/health — 헬스체크 엔드포인트

환경	트리거	URL 패턴	비고
개발	수동 (workflow_dispatch)	{branch}-app.	3일 후 자동 삭제
운영 Web	deploy-web-prod.yml		승인 후 배포
운영 Socket	deploy-socket-prod.yml	socket.	승인 후 배포

PPI Architecture Document · V2 (Mediasoup SFU) 기준 · 2026-05-20